// Copyright (c) 2014 Cloudera, Inc. All rights reserved.
package com.cloudera.api.v10;

import com.cloudera.api.v8.AuditsResourceV8;

import javax.ws.rs.Consumes;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.StreamingOutput;

import static com.cloudera.api.Parameters.DATE_TIME_NOW;
import static com.cloudera.api.Parameters.QUERY;

@Consumes({ MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_JSON })

/**
 * Fetches and streams the requested audit events.
 * <p>
 * By default, this call will fetch the first 100 audit events (sorted from most
 * recent to oldest) corresponding to a 1 day window based on provided end time
 * (which defaults to the  current CM server time). The <em>startTime</em> and
 * <em>endTime</em> parameters can be used to control the window being queried.
 * <p>
 * Audit events for CM managed services are only retrieved if Cloudera
 * Navigator server is running.
 *
 * @param maxResults Maximum number of audits to return
 * @param resultOffset Offset of audits to return
 * @param startTime Start of the period to query in ISO 8601 format (defaults
 * to 1 day ago relative to endTime).
 * @param endTime End of the period to query in ISO 8601 format. (defaults to
 * current time).
 * @param query
 *    The query to filter out audits in the system. It accepts
 *    querying the intersection of a list of constraints,
 *    joined together with semicolons (without spaces). For example:
 *    </p>
 *    <dl>
 *      <dt>command==listStatus</dt>
 *      <dd>looks for audits with listStatus command.</dd>
 *      <dt>command==listStatus;username!=foo</dt>
 *      <dd>looks for audits with listStatus command but excludes
 *      audits generated by foo username</dd>
 *      <dt>command==listStatus;source==*oozie*</dt>
 *      <dd>looks for audits with listStatus command and source that
 *          contains the string 'oozie'.
 *      </dd>
 *    </dl>
 *
 *    Following are valid selectors for the query (if applicable to the
 *    audit):
 *    <table>
 *      <tr>
 *        <th> Selector </th>
 *        <th> Description </th>
 *        <th> SCM </th>
 *        <th> HDFS </th>
 *        <th> HBase </th>
 *        <th> Hive </th>
 *        <th> Impala </th>
 *        <th> Sentry </th>
 *      </tr>
 *      <tr>
 *        <td> service </td>
 *        <td> Cloudera Manager Service </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> operation </td>
 *        <td> Operation name </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> username </td>
 *        <td> User name </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> impersonator</td>
 *        <td> Impersonator </td>
 *        <td> </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> ip_address </td>
 *        <td> IP Address </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> allowed </td>
 *        <td> Whether the request was allowed or denied </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> qualifier</td>
 *        <td> Column qualifier </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> x </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *      </tr>
 *      <tr>
 *        <td> source </td>
 *        <td> Source resource of the operation  </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> </td>
 *      </tr>
 *      <tr>
 *        <td> destination </td>
 *        <td> Destination resource of the operation </td>
 *        <td> </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> </td>
 *      </tr>
 *      <tr>
 *        <td> hostIpAddress </td>
 *        <td> Host IP Address </td>
 *        <td> x </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *      </tr>
 *      <tr>
 *        <td> role </td>
 *        <td> Cloudera Manager Role </td>
 *        <td> x </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *      </tr>
 *      <tr>
 *        <td> family </td>
 *        <td> Column family </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> x </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *      </tr>
 *      <tr>
 *        <td> database_name </td>
 *        <td> Database name </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> table_name </td>
 *        <td> Table name </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> object_type </td>
 *        <td> Type of object being handled </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *      <tr>
 *        <td> operation_text </td>
 *        <td> Command/query text </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> </td>
 *        <td> x </td>
 *        <td> x </td>
 *        <td> x </td>
 *      </tr>
 *    </table>
 *    <p>
 *    The only supported operator is <em>";"</em> (Boolean AND). Boolean OR is
 *    not supported.
 *    <p>
 *    The supported comparators are <em>==</em> and <em>!=</em>
 *    Note that "LIKE" comparison is supported using the wild card syntax,
 *    for example <em>foo==*value*</em>. Asterisk is interpreted as a wild
 *    card character and must not be part of the value. (LIKE comparison
 *    queries are converted to standard SQL LIKE syntax, so any % (%25)
 *    character in a value that also contains a wild card will be
 *    interpreted as a wild card.)
 *    <p>
 *    Values for time related query parameters (<em>startTime</em> and
 *    <em>endTime</em>) should be ISO8601 timestamps.
 * <p/>
 *
 * @return List of audits in descending order of timestamp
 */
public interface AuditsResourceV10 extends AuditsResourceV8 {

  @GET
  @Path("/stream")
  public StreamingOutput streamAudits(
      @QueryParam(value = "maxResults")
      @DefaultValue("100") Integer maxResults,
      @QueryParam(value = "resultOffset")
      @DefaultValue("0") Integer resultOffset,
      @QueryParam("startTime")
      String startTime,
      @QueryParam("endTime")
      @DefaultValue(DATE_TIME_NOW)
      String endTime,
      @QueryParam(QUERY) String query);
}
